How to Use the CleanTalk APIs for Your Personal Lists
API for managing Personal Lists. The interface is available here: cleantalk.org/my/show_private
Guide for the interface: cleantalk.org/help/blacklist-usage
Content:
General Information 
API private_list_get
API private_list_add
API private_list_delete
API private_list_update
General Information
Protocol - HTTPS
Hostname - api.cleantalk.org
API private_list_get
Input Parameters
Transfer parameters methods GET and POST.
Necessary
method_name allowed value: private_list_get
user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.
service_type allowed values: antispam, spamfirewall, securityfirewall
Example:
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam
Optional
service_id list filtration by the selected website, you can get your value in Anti-Spam Dashboard or in your Security Dashboard.
Example:
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&service_id=314956
record_type list filtration by the record type, allowed values:
- for service_type=antispam - 1, 2, 3, 4, 5, 7, 8, 9
- for service_type=spamfirewall - 6, 10
- for service_type=securityfirewall - 1, 3, 7
Example:
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&record_type=1
record_ids list filtration by the record ID
- Data array, example: record_ids[]=3985411&record_ids[]=3985397
- String, comma as a separator, example: record_ids=3985411,3985397
status list filtration by the record status, allowed values: allow, deny
created[lte] and created[gte] list filtration by the record creation date, allowed values: unix timestamp format
updated[lte] and updated[gte] list filtration by the record creation update, allowed values: unix timestamp format
search[value] search by the field "record", full or partial coincidence
start shift for the first record of the list, by default is 0
length limit of record quantity in the response, by default is 100, allowed values: 10, 25, 50, 100
order[0][dir] sorting direction of the records, allowed values: asc, desc
order[0][column] field index, records are being sorted by it
columns[0][data] field name of the record sorting, allowed values: record, record_type, created, updated, hits, status, product_id, hostname, note
draw arbitrary value, will be sent in the response for the asynchronous requests.
mode if its value is csv, the response will be an CSV file
Example:
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&service_type=antispam&mode=csv
Output Parameters
recordsTotal number of records without any filters
recordsFiltered number of records when filters are applied
draw arbitrary value, input parameters value
data record array:
- record_id record ID
- service_id website ID
- hostname website hosname
- record record value
- countrycode country code
- countryname country name
- hits number of hits for the past 7 days
- created record creation time
- updated record update time
- status record status
- record_type record type
- product_id product type
- note record note
- expired record lifespan
Example:
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN&draw=10&columns[0][data]=hits&columns[1][data]=record&columns[2][data]=record_type&columns[3][data]=created&order[0][column]=3&order[0][dir]=asc&start=0&length=10&service_type=antispam&service_id=314956&record_type=1
{"data":[{"record_id":"3689885","service_id":"314956","hostname":"example.com","record":"1.2.3.3","countrycode":"US","countryname":"United States","hits":null,"created":"2019-10-28 12:14:41","updated":"2019-10-28 12:14:41","status":"deny","record_type":"1","product_id":"1","note":"123","expired":null},{"record_id":"3890626","service_id":"314956","hostname":"example.com","record":"1.2.3.4","countrycode":"US","countryname":"United States","hits":null,"created":"2019-11-19 15:19:26","updated":"2019-11-19 15:19:26","status":"deny","record_type":"1","product_id":"1","note":"","expired":null}],"draw":"10","recordsTotal":"8","recordsFiltered":"2","currentPage":0}
Possible Errors
https://api.cleantalk.org/?method_name=private_list_get
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}
https://api.cleantalk.org/?method_name=private_list_get&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"31"}}
API private_list_add
Input Parameters
Necessary
method_name allowed value: private_list_add
user_token allowed value: you can get it in your dashboard in your CleanTalk Control Panel.
service_id website ID, use all to add to every website in your CleanTalk profile.
service_type service type, allowed values: antispam, spamfirewall, securityfirewall
product_id product ID, allowed values: 1 for service_type=antispam or service_type=spamfirewall, 4 for service_type=securityfirewall
record_type record type, allowed values:
- for service_type=antispam:
- 1 IP-address
- 2 E-mail
- 3 Country
- 4 Domain
- 5 Top-level domain
- 7 IP-network
- 8 Stop-word
- 9 Language
- for service_type=spamfirewall:
- 6 IP-network
- 10 Country
- for service_type=securityfirewall:
- 1 IP-address
- 3 Country
- 7 IP-network
records
- Data array, example: records[]=192.168.1.1&records[]=192.168.1.2
- String, comma as a separator, example: records=192.168.1.1,192.168.1.2
- File in the CSV format
Example:
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1
{"data":{"records":[{"record_id":3985397,"record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"SUCCESS"}]}}
Optional
note record note, no more than 2048 symbols
status record status, allowed values: allow, deny (default values), deny_except (allowed for countries only, excludes everything except the selected one)
expired date string, record lifespan
Example:
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow¬e=note&expired=2019-12-13 17:10:00
{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}
Output Parameters
records record array:
- record_id record ID
- service_id website ID
- hostname website hosname
- record record value
- countrycode country code
- created record creation time
- updated record update time
- status record status
- record_type record type
- product_id product type
- note record note
- expired record lifespan
- operation_status operation status
Example:
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.2&status=allow¬e=note&expired=2019-12-13 17:10:00
{"data":{"records":[{"record_id":3985411,"record":"192.168.1.2","created":"2019-12-13 19:11:02","updated":"2019-12-13 19:11:02","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"allow","note":"note","expired":"''2019-12-14 17:10:00''","countrycode":"","operation_status":"SUCCESS"}]}}
Possible Errors
https://api.cleantalk.org/?method_name=private_list_add
{"data":{"result":"FAIL","notice":"User token not found","operation_code":"51"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"service_id is required","operation_code":"2"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all
{"data":{"result":"FAIL","notice":"service_type is required and value must be in (antispam,spamfirewall,securityfirewall)","operation_code":"3"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam
{"data":{"result":"FAIL","notice":"product_id is required and value must be in (1,4)","operation_code":"4"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,2,3,4,5,7,8,9)","operation_code":"5"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=spamfirewall&product_id=1
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (6,10)","operation_code":"5"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=securityfirewall&product_id=4
{"data":{"result":"FAIL","notice":"record_type is required and value must be in (1,3,7)","operation_code":"5"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1
{"data":{"result":"FAIL","notice":"records is required","operation_code":"6"}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=mail@example.com
{"data":{"records":[{"record":"mail@example.com","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"Wrong format","operation_code":"7"}]}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=1.1.1.4
{"data":{"records":[{"record":"1.1.1.4","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","operation_status":"FAILED","operation_message":"This IP address belongs to networks of payment systems, searching systems or other important services. It is forbidden to add such address to your personal lists.","operation_code":"10"}]}}
https://api.cleantalk.org/?method_name=private_list_add&user_token=USER_TOKEN&service_id=all&service_type=antispam&product_id=1&record_type=1&records=192.168.1.1
{"data":{"records":[{"record_id":"3985397","record":"192.168.1.1","created":"2019-12-13 18:08:41","updated":"2019-12-13 18:08:41","service_id":"314956","service_type":"antispam","record_type":"1","product_id":"1","status":"deny","note":"","expired":"","countrycode":"","operation_status":"FAILED","operation_message":"Record already exists","operation_code":"9"}]}}
API private_list_delete
Input Parameters
method_name allowed value: private_list_delete
user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.
record_ids
- Data array, example: record_ids[]=3985411&record_ids[]=3985397
- String, comma as a separator, example: record_ids=3985411,3985397
Example:
https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}
Output Parameters
records record array:
- record_id record ID
- operation_status operation status
Example:
https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"SUCCESS"},{"record_id":"3985397","operation_status":"SUCCESS"}]}}
Possible Errors
https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"record_ids is required","operation_code":"22"}}
https://api.cleantalk.org/?method_name=private_list_delete&user_token=USER_TOKEN&record_ids=3985411,3985397
{"data":{"records":[{"record_id":"3985411","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"},{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"21"}]}}
API private_list_update
Input Parameters
method_name allowed value: private_list_update
user_token allowed values: you can get it in your dashboard in your CleanTalk Control Panel.
status[record_id] allowed values: allow и deny
note[record_id] maximum length is no more than 2048 symbols
Example:
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny&status[3982786]=deny
{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"},{"record_id":"3982786","operation_status":"SUCCESS"}]}}
Output Parameters
records record array:
- record_id record ID
- operation_status operation status
Example:
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=deny¬e[3803794]=test
{"data":{"records":[{"record_id":"3803794","operation_status":"SUCCESS"}]}}
Possible Errors
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN
{"data":{"result":"FAIL","notice":"record list is empty","operation_code":"43"}}
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN¬e[3985397]=note
{"data":{"records":[{"record_id":"3985397","operation_status":"FAILED","operation_message":"Record not found","operation_code":"42"}]}}
https://api.cleantalk.org/?method_name=private_list_update&user_token=USER_TOKEN&status[3803794]=allow
{"data":{"records":[{"record_id":"3803794","operation_status":"FAILED","operation_message":"status allow disabled for record_type in (3,8,6,10)","operation_code":"41"}]}}
It would also be interesting
- CleanTalk Anti-Spam check_newuser API MethodCleanTalk Anti-Spam "check_newuser" API method description This method is the best to filter spam signups,...
- How the CleanTalk Anti-Spam API Works. API Main HelpAPI Main Help Method "check_newuser" Method "check_message" Send_feedback Built-In...
- Spam Check API - API Method spam_checkAPI Method "spam_check" Common description Method's get parameters Response Explanation Multiple...